外部活动导入接口 (External Event Import)

接口概述

该接口用于从第三方活动平台导入活动数据到 Pear 系统。支持多个主流活动平台的导入，包括 Eventbrite、Poshvip、Raco、Shotgun 和 DiceFM。

[!important] 架构说明 本接口为 Admin Server 代理接口，实际业务逻辑由下游 Pear API 服务处理。Admin Server 负责请求转发和认证。

请求信息

基本参数

路径参数 (Path Parameters)

请求头 (Headers)

[!warning] 时区重要性 timezone 头信息会被转发到下游服务。某些活动平台（如 Poshvip）的时间解析依赖此时区信息，缺失可能导致 Failed to fetch timeZone 错误。

请求体 (Request Body)

请求结构

interface EventImportRequest {
  type: EventImportType;  // 活动来源平台类型
  url: string;            // 活动页面 URL
}

字段说明

type 枚举值

请求示例

{
  "type": "eventbrite",
  "url": "https://www.eventbrite.com/e/the-association-cocktail-classes-tickets-164264039163"
}

{
  "type": "poshvip",
  "url": "https://posh.vip/e/example-event"
}

响应信息

成功响应

[!note] 响应说明 实际响应结构由下游 Pear API 服务决定，Admin Server 透传下游响应的 data 字段。

interface SuccessResponse {
  // 响应结构由下游服务定义
  // 通常包含导入的活动信息
}

成功响应示例

{
  "id": "event-uuid-here",
  "title": "The Association Cocktail Classes",
  "description": "Event description...",
  "startTime": "2026-03-15T19:00:00Z",
  "endTime": "2026-03-15T22:00:00Z",
  "location": {
    "name": "Venue Name",
    "address": "123 Street, City"
  },
  // ... 其他活动字段
}

错误响应

错误响应结构

interface ErrorResponse {
  code: number;      // HTTP 状态码
  message: string;   // 错误信息
  data?: any;        // 附加错误详情（可选）
}

常见错误码

错误响应示例

参数验证失败 (400)

{
  "code": 400,
  "message": "type must be one of the following values: eventbrite, poshvip, raco, shotgun, dicefm",
  "data": null
}

时区获取失败 (500)

{
  "code": 500,
  "message": "Failed to fetch timeZone",
  "data": {
    "platform": "poshvip",
    "url": "https://posh.vip/e/xxx"
  }
}

活动 URL 无效

{
  "code": 400,
  "message": "Invalid event URL format",
  "data": {
    "url": "invalid-url"
  }
}

完整请求示例

cURL 示例

curl -X POST 'https://admin.katana-api.1m.app/users/tool/external-event-import/ad57de31-bf92-413b-ae4d-8609b5ff0680' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'timezone: Asia/Shanghai' \
  -H 'x-track-id: ac025c47-a2de-4634-8067-8642e14a24c4' \
  -d '{
    "type": "eventbrite",
    "url": "https://www.eventbrite.com/e/the-association-cocktail-classes-tickets-164264039163"
  }'

JavaScript (fetch) 示例

const response = await fetch(
  'https://admin.katana-api.1m.app/users/tool/external-event-import/ad57de31-bf92-413b-ae4d-8609b5ff0680',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
      'timezone': 'Asia/Shanghai',
      'x-track-id': crypto.randomUUID()
    },
    body: JSON.stringify({
      type: 'eventbrite',
      url: 'https://www.eventbrite.com/e/the-association-cocktail-classes-tickets-164264039163'
    })
  }
);

const result = await response.json();

下游服务请求 (Pear API)

Admin Server 通过 RPC 调用下游 Pear API 服务，以下是转发请求的详细参数。

[!tip] 内部服务调用 此部分为 Admin Server 与 Pear API 之间的内部通信，供后端开发参考。

请求信息

请求头 (Headers)

Admin Server 会自动添加以下认证头：

[!note] 头信息传递 客户端传递的 timezone、x-track-id 等头信息也会被转发到下游服务。

请求体 (Body)

请求体直接透传，与客户端请求体一致：

{
  "type": "eventbrite",
  "url": "https://www.eventbrite.com/e/xxx-tickets-123456789"
}

完整请求示例

# Admin Server -> Pear API 内部调用
curl -X POST '${KATANA_URL}/external-event-import/admin/ad57de31-bf92-413b-ae4d-8609b5ff0680' \
  -H 'Content-Type: application/json' \
  -H 'Pear-Client-Id: ${PEAR_CLIENT_ID}' \
  -H 'Pear-Client-Secret: ${PEAR_CLIENT_SECRET}' \
  -H 'timezone: Asia/Shanghai' \
  -d '{
    "type": "eventbrite",
    "url": "https://www.eventbrite.com/e/the-association-cocktail-classes-tickets-164264039163"
  }'

响应处理

下游 Pear API 返回格式：

interface PearApiResponse<T> {
  data: T;  // Admin Server 提取此字段返回给客户端
}

Admin Server 提取 response.data.data 作为最终响应返回给客户端。

RPC Service 实现

// src/rpc/rpc.service.ts

async requestToPear<T = any>(
  url: string,
  config?: Parameters<typeof axios>[1],
): Promise<T> {
  try {
    const result = await axios(url, {
      baseURL: this.configService.get<string>('KATANA_URL'),
      ...config,
      headers: {
        ['Pear-Client-Id']: this.configService.get('PEAR_CLIENT_ID'),
        ['Pear-Client-Secret']: this.configService.get('PEAR_CLIENT_SECRET'),
        ...config?.headers,  // 合并额外的 headers
      },
    });
    return result.data.data as T;  // 提取 data.data 返回
  } catch (error: any) {
    throw new CustomException(
      error?.response?.status ?? 409,
      error?.response?.data?.message,
      error?.response?.data?.data,
    );
  }
}

业务逻辑

处理流程

    participant Client as 客户端
    participant Admin as Admin Server
    participant Pear as Pear API (下游服务)
    participant Platform as 第三方平台

    Client->>Admin: POST /external-event-import/:userId
    Note over Client,Admin: Headers: Authorization, timezone
    Note over Client,Admin: Body: {type, url}

    Admin->>Admin: JWT 认证验证
    Admin->>Admin: 参数验证 (class-validator)

    Admin->>Pear: POST /external-event-import/admin/:userId
    Note over Admin,Pear: 转发请求体和 Headers

    Pear->>Platform: 爬取/解析活动数据
    Platform-->>Pear: 返回活动信息

    Pear->>Pear: 创建活动记录
    Pear-->>Admin: 返回活动数据

    Admin-->>Client: 透传响应数据

架构说明

[!info] 代理模式 Admin Server 采用代理模式，核心职责包括：

1. 认证鉴权：验证 JWT Token 有效性
2. 参数校验：使用 class-validator 验证请求参数
3. 请求转发：通过 RPC 调用下游 Pear API 服务
4. 错误处理：捕获下游异常并转换为统一错误格式

关键代码位置

注意事项

必读事项

[!danger] 认证要求

• 所有请求必须携带有效的 JWT Bearer Token
• Token 通过 Authorization 头传递
• 未认证请求将返回 401 Unauthorized

[!warning] 时区设置

• 强烈建议始终传递 timezone 头
• 格式为 IANA 时区标识符，如 Asia/Shanghai、America/New_York
• 缺失可能导致部分平台导入失败

[!caution] URL 有效性

• 确保 URL 为目标平台的有效活动页面
• URL 必须可公开访问（无需登录即可查看）
• 私有或已下线的活动可能无法导入

平台特定说明

错误排查

相关接口

• [[kat-music-widget-import-音乐组件导入]] - 音乐组件导入接口
• [[kat-external-user-import-外部用户导入]] - Partner/Promoter 用户导入
• [[kat-web-scraper-网页爬虫]] - Komi/Linktr 爬虫接口

变更历史

附录

EventImportRequest 类型定义

// src/users/user.interface.ts

export enum EventImportType {
  EVENTBRITE = 'eventbrite',
  POSHVIP = 'poshvip',
  RACO = 'raco',
  SHOTGUN = 'shotgun',
  DICEFM = 'dicefm',
}

export class EventImportRequest {
  @IsEnum(EventImportType)
  type: EventImportType;

  @IsString()
  url: string;
}

Controller 实现

// src/users/users.tool.controller.ts

@Post('external-event-import/:userId')
async importEvent(
  @Param('userId') userId: string,
  @Body() body: EventImportRequest,
) {
  return this.rpcService.requestToPear(
    `external-event-import/admin/${userId}`,
    {
      method: 'POST',
      data: body,
    },
  );
}